.\" Copyright (c) Rong Tao (rtoax@foxmail.com)
.\"
.\" SPDX-License-Identifier: GPL-2.0-or-later
.\"
.TH ulpatch 8  "2022-10-01" "USER COMMANDS"
.SH NAME
ulpatch \- Userspace livepatch.

.SH SYNOPSIS
.B ulpatch
[\fI\,OPTION\/\fR]...

.SH DESCRIPTION
.\" Add any additional description here
.PP
ulpatch is the core tool of ULPatch, which is used to manage the patch of the target process, including patch loading, patch unloading, and multi-patch management.

This program is a basic command of ULPatch.

.SH REQUIREMENTS
bfd

.SH ARGUMENTS
.SS
\fB\-p\fR, \fB\-\-pid\fR [PID]
Specify a target process's PID.

.SS
\fB\-\-patch\fR [ULPATCH.ELF]
Specify a ulpatch.elf file to patch to target process.

.SS
\fB\-\-unpatch\fR
Unpatch a latest ulpatch from target process.

.SS
\fB\-\-map-pfx\fR
Display prefix of ulp in
.IR /proc/ [PID] /maps .

.SH COMMON ARGUMENTS
.SS
\fB\-\-log-level\fR[=\fI\,LEVEL\/\fR], \fB\-\-lv\fR[=\fI\,LEVEL\/\fR]
Specify a log level. The LEVEL could be number(see
.BR syslog (3)
) or string(debug,dbg,info,inf,notice,note,warning,warn,error,err,crit,alert,emerg).
For example, if you want to set log level to LOG_ERR, just:
.BR --lv=error .

.SS
\fB\-\-log-debug\fR
Set log level to DEBUG.

.SS
\fB\-\-log-error\fR
Set log level to ERROR.

.SS
\fB\-u\fR, \fB\-\-dry-run\fR
Don't actually run.

.SS
\fB\-v\fR[vvv...], \fB\-\-verbose\fR
Show verbose information.
You can set more \fBv\fR values to increase the verbose level and display more details.
For example, \fB-vvvvv\fR will set the verbose value to \fB4\fR, because there are 4 \fBv\fR's.

.SS
\fB\-h\fR, \fB\-\-help\fR
Show help information.

.SS
\fB\-V\fR, \fB\-\-version\fR
Show version information.

.SS
\fB\-F\fR, \fB\-\-force\fR
Force do something.

.SS
\fB\-\-info\fR
Print detailed information about features supported by the kernel and the ULPatch build. It is necessary to display this information when you are submitting a MR/PR.

.SH MACROS
.SS
.B __ULP_DEV
If you develope an ulpatch ulp file, you need to define
.B __ULP_DEV
and include
.B <ulpatch/meta.h>
header in your ulpatch source code. The
.BR ulpconfig (8)
.B --cflags
provides this macro.

.SH ULP DEMO
More to see the documentations in ulpatch source code tree.
.SS Program source
\&
.\" SRC BEGIN (tee.c)
.EX
#ifndef __ULP_DEV
#define __ULP_DEV 1
#endif
#include <stdio.h>
#include <ulpatch/asm.h>
#include <ulpatch/meta.h>

void ulpatch_print_hello_exit(void)
{
	printf("Patched.\\n");
	__ulp_builtin_exit(0xff);
}
ULPATCH_INFO(ulpatch_print_hello_exit, print_hello, "Rong Tao");
.EE
.\" SRC END

.SH ARCHITECTURES
List the CPU architectures that ULPatch supports and will support.
.TS
allbox;
lbx lb lb
l l l.
Architecture	Supported	Value
T{
.na
.nh
.BR x86_64
T}	YES	TODO
T{
.na
.nh
.BR aarch64
T}	YES	TODO
T{
.na
.nh
.BR loongarch64
T}	NO	-
T{
.na
.nh
.BR riscv64
T}	NO	-
.TE

.SH SUPPORT_TYPE

.TS
allbox;
lbx lb lb
l l l.
Execution	Patch-Type	Supported
T{
.na
.nh
.BR ET_EXEC
T}	Add-Variable	yes
T{
.na
.nh
.BR ET_EXEC
T}	Call-Library-Function	yes
T{
.na
.nh
.BR ET_DYN
T}	Add-Variable	not-yet
T{
.na
.nh
.BR ET_DYN
T}	Call-Library-Function	not-yet
.TE

.SH SELFTESTS
Use \fBulpatch_test\fR command to test.

.SH LINKS
.IP " 1." 4
aarch64 relocations
.RS 4
\%https://github.com/ARM-software/abi-aa/releases
\%https://github.com/ARM-software/abi-aa/blob/main/aaelf64/aaelf64.rst
\%https://docslib.org/doc/4448214/elf-for-the-arm-64-bit-architecture-aarch64

.SH OS
Linux

.SH STABILITY
Unstable - in development.

.SH AUTHOR
Written by Rong Tao

.SH SEE ALSO
.BR ulpinfo (8),
.BR ulftrace (8),
.BR ultask (8),
.BR ulpconfig (8)

.P
The descriptions of the following files in
.BR proc (5):
.IR /proc/ pid /maps ,
.IR /proc/ pid /map_files ,
and
.IR /proc/ pid /smaps .
